package cn.bonoon.kernel.annotations;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * <pre>
 * 定义数据库实体和界面实体两个实体之间数据的转换。
 * 
 * 没有使用该注解标注的，则表示是单字段的转换，可以直接从数据库实体到界面实体
 * 也可以直接从界面实体到数据库实体.
 * 
 * 版本1.1:
 *     添加对树形结构的读取值的支持
 *     
 * 版本3.0：
 *     支持普通对象为数组或集合，数据库实体的字段为字符串，则可以把该数组或集合解析成字符串
 * 解析过程可以定义分隔符，如果是从字符串解析到普通对象的，则可以根据指定的类型来创建该对象，
 * 具体的用户详见{@link ArraySeparator}
 *     简化关联关系之间的指定，如：<code>AccountEntity.place</code>在进行关联关系处理的指定的时候，可以直接使用
 * <code>private Long place;</code>
 * 定义，也可以使用
 * <code>private @TransformField("place.id") Long place;</code>
 * 在处理的时候，会自动把<code>place.id</code>后面的".id"自动去掉
 *     支持使用定义的名称与字段名称的合并方式，如：
 * <code>private @TransformField("place.") Long name;</code>
 * 以"."结束，组合起来就表示"place.name"
 * </pre>
 * 
 * <pre>
 * 可以通过指定为"不读和不写"为忽略该字段的转值，虽然转值被忽略了，但使用其它注解依然有效，
 * 这就是与{@link Ignore}的区别
 * </pre>
 * 
 * @author jackson
 * @version 1.1
 * 
 * @see Transform
 */
@Target(FIELD)
@Retention(RUNTIME)
public @interface TransformField {

	/** propertyName */
	String value() default "";

	/** <pre> 是否只从实体读值，只有指定了转换的模式为TWOWAY的模式下，readOnly才有率，
	 * 否则都只从数据库实体取值，不会对数据库实体进行赋值  </pre> */
	WriteModel writable() default WriteModel.WRITABLE;

	/** 是否允许读值 */
	boolean readable() default true;
	
	/**
	 * <pre>
	 * 如果向数据库实体写值，遇到null的情况，是忽略null值还是把该字段设置为null。
	 * 
	 * 忽略null值的意思是：原来字段是什么值就是什么值，不会把它赋为null值
	 * 只有非基本类型的数据才有这样的功能；适用于向数据库实体写值和取值
	 * 
	 * 并且使用某些特殊的指定的时候，该属性的指定无效，包括：
	 * 1.自动生成编码的指定
	 * 2.生成MD5码的指定
	 * </pre>
	 */
	boolean writeIgnoreNull() default false;
}
